home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / share / automake-1.8 / Automake / ChannelDefs.pm next >
Encoding:
Perl POD Document  |  2005-10-16  |  9.5 KB  |  402 lines
  1. # Copyright (C) 2002, 2003 Free Software Foundation, Inc.
  2.  
  3. # This program is free software; you can redistribute it and/or modify
  4. # it under the terms of the GNU General Public License as published by
  5. # the Free Software Foundation; either version 2, or (at your option)
  6. # any later version.
  7.  
  8. # This program is distributed in the hope that it will be useful,
  9. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  10. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11. # GNU General Public License for more details.
  12.  
  13. # You should have received a copy of the GNU General Public License
  14. # along with this program; if not, write to the Free Software
  15. # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  16. # 02111-1307, USA.
  17.  
  18. package Automake::ChannelDefs;
  19.  
  20. use Automake::Channels;
  21.  
  22. =head1 NAME
  23.  
  24. Automake::ChannelDefs - channel definitions for Automake and helper functions
  25.  
  26. =head1 SYNOPSIS
  27.  
  28.   use Automake::ChannelDefs;
  29.  
  30.   Automake::ChannelDefs::usage ();
  31.   prog_error ($MESSAGE, [%OPTIONS]);
  32.   error ($WHERE, $MESSAGE, [%OPTIONS]);
  33.   error ($MESSAGE);
  34.   fatal ($WHERE, $MESSAGE, [%OPTIONS]);
  35.   fatal ($MESSAGE);
  36.   verb ($MESSAGE, [%OPTIONS]);
  37.   switch_warning ($CATEGORY);
  38.   parse_WARNINGS ();
  39.   parse_warning ($OPTION, $ARGUMENT);
  40.   Automake::ChannelDefs::set_strictness ($STRICTNESS_NAME);
  41.  
  42. =head1 DESCRIPTION
  43.  
  44. This packages defines channels that can be used in Automake to
  45. output diagnostics and other messages (via C<msg()>).  It also defines
  46. some helper function to enable or disable these channels, and some
  47. shorthand function to output on specific channels.
  48.  
  49. =cut
  50.  
  51. use 5.005;
  52. use strict;
  53. use Exporter;
  54.  
  55. use vars qw (@ISA @EXPORT);
  56.  
  57. @ISA = qw (Exporter);
  58. @EXPORT = qw (&prog_error &error &fatal &verb
  59.           &switch_warning &parse_WARNINGS &parse_warnings);
  60.  
  61. =head2 CHANNELS
  62.  
  63. The following channels can be used as the first argument of
  64. C<Automake::Channel::msg>.  For some of them we list a shorthand
  65. function that makes the code more readable.
  66.  
  67. =over 4
  68.  
  69. =item C<fatal>
  70.  
  71. Fatal errors.  Use C<&fatal> to send messages over this channel.
  72.  
  73. =item C<error>
  74.  
  75. Common errors.   Use C<&error> to send messages over this channel.
  76.  
  77. =item C<error-gnu>
  78.  
  79. Errors related to GNU Standards.
  80.  
  81. =item C<error-gnu/warn>
  82.  
  83. Errors related to GNU Standards that should be warnings in `foreign' mode.
  84.  
  85. =item C<error-gnits>
  86.  
  87. Errors related to GNITS Standards (silent by default).
  88.  
  89. =item C<automake>
  90.  
  91. Internal errors.  Use C<&prog_error> to send messages over this channel.
  92.  
  93. =item C<gnu>
  94.  
  95. Warnings related to GNU Coding Standards.
  96.  
  97. =item C<obsolete>
  98.  
  99. Warnings about obsolete features (silent by default).
  100.  
  101. =item C<override>
  102.  
  103. Warnings about user redefinitions of Automake rules or
  104. variables (silent by default).
  105.  
  106. =item C<portability>
  107.  
  108. Warnings about non-portable constructs.
  109.  
  110. =item C<syntax>
  111.  
  112. Warnings about weird syntax, unused variables, typos...
  113.  
  114. =item C<unsupported>
  115.  
  116. Warnings about unsupported (or mis-supported) features.
  117.  
  118. =item C<verb>
  119.  
  120. Messages output in C<--verbose> mode.  Use C<&verb> to send such messages.
  121.  
  122. =item C<note>
  123.  
  124. Informative messages.
  125.  
  126. =back
  127.  
  128. =cut
  129.  
  130. # Initialize our list of error/warning channels.
  131. # Do not forget to update &usage and the manual
  132. # if you add or change a warning channel.
  133.  
  134. register_channel 'fatal', type => 'fatal';
  135. register_channel 'error', type => 'error';
  136. register_channel 'error-gnu', type => 'error';
  137. register_channel 'error-gnu/warn', type => 'error';
  138. register_channel 'error-gnits', type => 'error', silent => 1;
  139. register_channel 'automake', type => 'fatal', backtrace => 1,
  140.   header => ("####################\n" .
  141.          "## Internal Error ##\n" .
  142.          "####################\n"),
  143.   footer => "\nPlease contact <bug-automake\@gnu.org>.";
  144.  
  145. register_channel 'gnu', type => 'warning';
  146. register_channel 'obsolete', type => 'warning', silent => 1;
  147. register_channel 'override', type => 'warning', silent => 1;
  148. register_channel 'portability', type => 'warning', silent => 1;
  149. register_channel 'syntax', type => 'warning';
  150. register_channel 'unsupported', type => 'warning';
  151.  
  152. register_channel 'verb', type => 'debug', silent => 1;
  153. register_channel 'note', type => 'debug', silent => 0;
  154.  
  155. =head2 FUNCTIONS
  156.  
  157. =over 4
  158.  
  159. =item C<usage ()>
  160.  
  161. Display warning categories.
  162.  
  163. =cut
  164.  
  165. sub usage ()
  166. {
  167.   print "Warning categories include:
  168.   `gnu'           GNU coding standards (default in gnu and gnits modes)
  169.   `obsolete'      obsolete features or constructions
  170.   `override'      user redefinitions of Automake rules or variables
  171.   `portability'   portability issues
  172.   `syntax'        dubious syntactic constructs (default)
  173.   `unsupported'   unsupported or incomplete features (default)
  174.   `all'           all the warnings
  175.   `no-CATEGORY'   turn off warnings in CATEGORY
  176.   `none'          turn off all the warnings
  177.   `error'         treat warnings as errors
  178. ";
  179. }
  180.  
  181. =item C<prog_error ($MESSAGE, [%OPTIONS])>
  182.  
  183. Signal a programming error (on channel C<automake>),
  184. display C<$MESSAGE>, and exit 1.
  185.  
  186. =cut
  187.  
  188. sub prog_error ($;%)
  189. {
  190.   my ($msg, %opts) = @_;
  191.   msg 'automake', '', $msg, %opts;
  192. }
  193.  
  194. =item C<error ($WHERE, $MESSAGE, [%OPTIONS])>
  195.  
  196. =item C<error ($MESSAGE)>
  197.  
  198. Uncategorized errors.
  199.  
  200. =cut
  201.  
  202. sub error ($;$%)
  203. {
  204.   my ($where, $msg, %opts) = @_;
  205.   msg ('error', $where, $msg, %opts);
  206. }
  207.  
  208. =item C<fatal ($WHERE, $MESSAGE, [%OPTIONS])>
  209.  
  210. =item C<fatal ($MESSAGE)>
  211.  
  212. Fatal errors.
  213.  
  214. =cut
  215.  
  216. sub fatal ($;$%)
  217. {
  218.   my ($where, $msg, %opts) = @_;
  219.   msg ('fatal', $where, $msg, %opts);
  220. }
  221.  
  222. =item C<verb ($MESSAGE, [%OPTIONS])>
  223.  
  224. C<--verbose> messages.
  225.  
  226. =cut
  227.  
  228. sub verb ($;%)
  229. {
  230.   my ($msg, %opts) = @_;
  231.   msg 'verb', '', $msg, %opts;
  232. }
  233.  
  234. =item C<switch_warning ($CATEGORY)>
  235.  
  236. If C<$CATEGORY> is C<mumble>, turn on channel C<mumble>.
  237. If it's C<no-mumble>, turn C<mumble> off.
  238. Else handle C<all> and C<none> for completeness.
  239.  
  240. =cut
  241.  
  242. sub switch_warning ($)
  243. {
  244.   my ($cat) = @_;
  245.   my $has_no = 0;
  246.  
  247.   if ($cat =~ /^no-(.*)$/)
  248.     {
  249.       $cat = $1;
  250.       $has_no = 1;
  251.     }
  252.  
  253.   if ($cat eq 'all')
  254.     {
  255.       setup_channel_type 'warning', silent => $has_no;
  256.     }
  257.   elsif ($cat eq 'none')
  258.     {
  259.       setup_channel_type 'warning', silent => ! $has_no;
  260.     }
  261.   elsif ($cat eq 'error')
  262.     {
  263.       $warnings_are_errors = ! $has_no;
  264.       # Set exit code if Perl warns about something
  265.       # (like uninitialized variables).
  266.       $SIG{"__WARN__"} =
  267.     $has_no ? 'DEFAULT' : sub { print STDERR @_; $exit_code = 1; };
  268.     }
  269.   elsif (channel_type ($cat) eq 'warning')
  270.     {
  271.       setup_channel $cat, silent => $has_no;
  272.     }
  273.   else
  274.     {
  275.       return 1;
  276.     }
  277.   return 0;
  278. }
  279.  
  280. =item C<parse_WARNINGS ()>
  281.  
  282. Parse the WARNINGS environment variable.
  283.  
  284. =cut
  285.  
  286. sub parse_WARNINGS ()
  287. {
  288.   if (exists $ENV{'WARNINGS'})
  289.     {
  290.       # Ignore unknown categories.  This is required because WARNINGS
  291.       # should be honored by many tools.
  292.       switch_warning $_ foreach (split (',', $ENV{'WARNINGS'}));
  293.     }
  294. }
  295.  
  296. =item C<parse_warning ($OPTION, $ARGUMENT)>
  297.  
  298. Parse the argument of C<--warning=CATEGORY> or C<-WCATEGORY>.
  299.  
  300. C<$OPTIONS> is C<"--warning"> or C<"-W">, C<$ARGUMENT> is C<CATEGORY>.
  301.  
  302. This is meant to be used as a argument to C<Getopt>.
  303.  
  304. =cut
  305.  
  306. sub parse_warnings ($$)
  307. {
  308.   my ($opt, $categories) = @_;
  309.  
  310.   foreach my $cat (split (',', $categories))
  311.     {
  312.       msg 'unsupported', "unknown warning category `$cat'"
  313.     if switch_warning $cat;
  314.     }
  315. }
  316.  
  317. =item C<set_strictness ($STRICTNESS_NAME)>
  318.  
  319. Configure channels for strictness C<$STRICTNESS_NAME>.
  320.  
  321. =cut
  322.  
  323. sub set_strictness ($)
  324. {
  325.   my ($name) = @_;
  326.  
  327.   # FIXME: 'portability' warnings are currently disabled by default.
  328.   # Eventually we want to turn them on in GNU and GNITS modes, but
  329.   # we don't do this yet in Automake 1.7 to help the 1.6/1.7 transition.
  330.   #
  331.   # Indeed there would be only two ways to get rid of these new warnings:
  332.   #  1. adjusting Makefile.am
  333.   #     This is not always easy (or wanted).  Consider %-rules or
  334.   #     $(function args) variables.
  335.   #  2. using -Wno-portability
  336.   #     This means there is no way to have the same Makefile.am
  337.   #     working both with Automake 1.6 and 1.7 (since 1.6 does not
  338.   #     understand -Wno-portability).
  339.   #
  340.   # In Automake 1.8 (or whatever it is called) we can turn these
  341.   # warnings on, since -Wno-portability will not be an issue for
  342.   # the 1.7/1.8 transition.
  343.  
  344.   if ($name eq 'gnu')
  345.     {
  346.       setup_channel 'error-gnu', silent => 0;
  347.       setup_channel 'error-gnu/warn', silent => 0, type => 'error';
  348.       setup_channel 'error-gnits', silent => 1;
  349.       # setup_channel 'portability', silent => 0;
  350.       setup_channel 'gnu', silent => 0;
  351.     }
  352.   elsif ($name eq 'gnits')
  353.     {
  354.       setup_channel 'error-gnu', silent => 0;
  355.       setup_channel 'error-gnu/warn', silent => 0, type => 'error';
  356.       setup_channel 'error-gnits', silent => 0;
  357.       # setup_channel 'portability', silent => 0;
  358.       setup_channel 'gnu', silent => 0;
  359.     }
  360.   elsif ($name eq 'foreign')
  361.     {
  362.       setup_channel 'error-gnu', silent => 1;
  363.       setup_channel 'error-gnu/warn', silent => 0, type => 'warning';
  364.       setup_channel 'error-gnits', silent => 1;
  365.       # setup_channel 'portability', silent => 1;
  366.       setup_channel 'gnu', silent => 1;
  367.     }
  368.   else
  369.     {
  370.       prog_error "level `$name' not recognized\n";
  371.     }
  372. }
  373.  
  374. =back
  375.  
  376. =head1 SEE ALSO
  377.  
  378. L<Automake::Channels>
  379.  
  380. =head1 HISTORY
  381.  
  382. Written by Alexandre Duret-Lutz E<lt>F<adl@gnu.org>E<gt>.
  383.  
  384. =cut
  385.  
  386. ### Setup "GNU" style for perl-mode and cperl-mode.
  387. ## Local Variables:
  388. ## perl-indent-level: 2
  389. ## perl-continued-statement-offset: 2
  390. ## perl-continued-brace-offset: 0
  391. ## perl-brace-offset: 0
  392. ## perl-brace-imaginary-offset: 0
  393. ## perl-label-offset: -2
  394. ## cperl-indent-level: 2
  395. ## cperl-brace-offset: 0
  396. ## cperl-continued-brace-offset: 0
  397. ## cperl-label-offset: -2
  398. ## cperl-extra-newline-before-brace: t
  399. ## cperl-merge-trailing-else: nil
  400. ## cperl-continued-statement-offset: 2
  401. ## End:
  402.